Skip to main content
POST
/
api
/
v1
/
instances
Deploy a new instance (catalog-driven via `variantId` or explicit).
curl --request POST \
  --url https://openapi.beeos.ai/api/v1/instances \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "<string>",
  "variantId": "<string>",
  "agentFramework": "<string>",
  "providerId": "<string>",
  "providerConfig": {},
  "modelPrimary": "<string>",
  "models": [
    "<string>"
  ],
  "systemPrompt": "<string>",
  "mcpServers": {},
  "bridgeId": "<string>",
  "config": {},
  "clusterId": "<string>",
  "preferredRegion": "<string>"
}
'
{
  "success": true,
  "data": {
    "id": "<string>",
    "ownerId": "<string>",
    "agentFramework": "<string>",
    "providerId": "<string>",
    "externalId": "<string>",
    "osType": "<string>",
    "hostingType": "<string>",
    "cloudProvider": "<string>",
    "name": "<string>",
    "modelPrimary": "<string>",
    "models": [
      "<string>"
    ],
    "status": "<string>",
    "desiredStatus": "<string>",
    "endpoint": "<string>",
    "bridgeId": "<string>",
    "identityId": "<string>",
    "totalRunSeconds": 123,
    "connectivity": "<string>",
    "providerConfig": {},
    "connectivityReason": "device_disconnected",
    "haltReason": "<string>",
    "publicIp": "<string>",
    "clusterId": "<string>",
    "region": "<string>",
    "imageId": "<string>",
    "imageRef": "<string>",
    "isTrial": true,
    "expiresAt": "2023-11-07T05:31:56Z",
    "errorMessage": "<string>",
    "systemPrompt": "<string>",
    "mcpServers": {},
    "startedAt": "2023-11-07T05:31:56Z",
    "stoppedAt": "2023-11-07T05:31:56Z",
    "statusEnteredAt": "2023-11-07T05:31:56Z",
    "connectivityUpdatedAt": "2023-11-07T05:31:56Z",
    "createdAt": "2023-11-07T05:31:56Z",
    "updatedAt": "2023-11-07T05:31:56Z",
    "screenshotUrl": "<string>",
    "screenshotUpdatedAt": "2023-11-07T05:31:56Z"
  }
}

Authorizations

​
Authorization
string
header
required

Pass a user JWT or a oag_ User API Key on the Authorization: Bearer <token> header. Both are validated by openapi-gateway against the Auth service.

Both credential types are user-scoped: every key (and every JWT) is bound to exactly one owner, and every route grants the caller full access to that owner's own resources. Cross-tenant access is denied by owner-ACL inside the handlers — there is no per-route scope vocabulary on this API.

Removed in v1.1.0: the legacy agents:* / tasks:* / files:* / instances:* scope set has been dropped together with the 403 insufficient_scope error. Existing oag_ keys automatically gain full owner-level access and do not need to be re-issued. SDK calls that previously passed scopes to createAPIKey should drop the argument. See the changelog at the bottom of this spec for the full migration note.

Body

application/json

Either supply a catalog variantId (authoritative — lifts agentFramework / providerId / region / scheduling hints from the variant) or provide an explicit agentFramework (+ optional providerId). Client-supplied scheduling fields (ownershipPreference / maxPricePerHour / resourceTypeHint) are not accepted here; the catalog variant is the source of truth.

​
name
string
required
Maximum string length: 128
​
variantId
string
Maximum string length: 128
​
agentFramework
string
Maximum string length: 64
​
providerId
string
Maximum string length: 64
​
providerConfig
object

Free-form provider-specific configuration merged with the catalog config (catalog wins on key conflicts).

​
modelPrimary
string
Maximum string length: 128
​
models
string[]
Maximum string length: 128
​
systemPrompt
string
Maximum string length: 8192
​
mcpServers
object
​
bridgeId
string
Maximum string length: 128
​
config
object

Alternate name for providerConfig; same semantics. Used by the variant-driven path to layer user extras (apiKeys / apiBaseUrls) on top of the catalog config.

​
clusterId
string
Maximum string length: 128
​
preferredRegion
string
Maximum string length: 64

Response

Standard envelope; data is the created instance.

​
success
boolean
required
​
data
object
required